Summary

• graduate the Session subsystem from src/experimental/memory/session to the canonical src/sessions boundary
• publish Session APIs and their compaction/token utilities through agents/sessions
• keep agents/experimental/memory/session and agents/experimental/memory/utils as deprecated compatibility re-exports
• move Think, examples, tests, and user-facing docs to the stable import path
• preserve Session providers, SQLite/Postgres storage behavior, context blocks, search, skills, compaction, and message protocol behavior

API

import {
  Session,
  SessionManager,
  AgentSessionProvider,
  createCompactFunction,
  estimateMessageTokens
} from "agents/sessions";

The old package paths remain valid:

import { Session } from "agents/experimental/memory/session";
import { createCompactFunction } from "agents/experimental/memory/utils";

They now re-export the canonical implementation and are documented as deprecated.

Lifecycle relationship

This follows the component-ownership direction established in #1895, but does not add another Agent lifecycle hook. Session already owns lazy, idempotent initialization through Session.create(...) and _ensureReady(), including provider initialization and hibernation restoration. Moving that logic into Agent startup would make Session less composable for direct providers and multi-session use.

The general pattern is therefore:

• the subsystem owns its initialization and storage behavior
• Agent/Think consume it through a narrow public component API
• the generic Agent lifecycle is used only when the host must coordinate a runtime phase

Compatibility

• no Session runtime or storage schema changes
• @cloudflare/think continues to re-export Session and SessionMessage
• old experimental package imports continue to resolve
• compaction and token utilities graduate with Session so stable Session examples do not depend on an experimental path

Verification

• pnpm --filter agents exec vitest --run --project workers src/tests/sessions
• pnpm --filter @cloudflare/think test:workers
• pnpm run build
• pnpm run check
• CI=true pnpm exec nx affected -t test

All checks pass. This draft is stacked on #1895 and targets feat/standardise-agent-lifecycle.